Icon Resources
desktop, you can design your own icons for all the files associated with your
application, including
• your application file itself
• standard documents created by your application
• stationery pads that users create from your application's documents
• data-sharing editions that users create from your application's
documents
• other special documents, such as read-only, graphics, and query
documents, which are either created by your Macintosh application or
provided by you for use by other Macintosh applications
For most effective display, you should create an icon family for each
single object, such as an application or document, on the desktop. An
entire icon family consists of
• a large (32-by-32 pixel) black-and-white icon and mask ( resource
• a small (16-by-16 pixel) black-and-white icon and mask ( resource
• a large (32-by-32 pixel) color icon with 4 bits of color data per
pixel (resource type 'icl4')
• a small (16-by-16 pixel) color icon with 4 bits of color data per
pixel (resource type 'ics4')
• a large (32-by-32 pixel) color icon with 8 bits of color data per
pixel (resource type 'icl8')
• a small (16-by-16 pixel) color icon with 8 bits of color data per
pixel (resource type 'ics8')
application and document icons for display. The following figure shows the
System 7.0 also displays desk accessories with icons.
Default large black-and-white icons
application, desk accessory, or documents, you must at least define an 'ICN#'
resource (called an icon list ) for each icon. The two icons defined in the 'ICN#'
resource are a 32-by-32 pixel, black-and-white icon and its mask. You can
also define color and 16-by-16 pixel icons in other resources described in
black-and-white icon defined in your 'ICN#' resource on all displays, and if
the 32-by-32 pixel icon to half size when needed.
the actual icon for display on the desktop and an all-black mask that shows the
draws the icon into this shape. Therefore, it's important that the mask be
exactly the same shape as the icon. The mask also defines the area that users
need to click to select the icon. Therefore, it's best not to have any holes in the
mask; otherwise, users may have trouble selecting your icon. The following
figure shows an application icon and its mask.
An application icon and its mask
use a high-level tool like the ResEdit application, which is available through
APDA, to create your 'ICN#' resources.
The following is a partial listing of the Rez input for the 'ICN#' resources
shown in this figure. This listing and those that follow use Rez format to help
you understand the format of the resources and see how they work together.
'ICN#' resources for an application and its documents
{ /* array: 2 elements */
/* first element: the application icon */
$"00 11 E2 00" /* each line holds 4 bytes (32 bits) */
/* 32 lines total for icon */
$"00 00 0F 00" /* 32nd line of icon */
, /* second element: the mask */
$"00 00 FF 00
/* 32 lines total for icon */
$"00 00 0F 00" /* 32nd line of mask */
}
};
{ /* icon data goes here */
}
};
{ /* icon data goes here */
}
};
{ /* icon data goes here */
}
};
You can also define a small (16-by-16 pixel) version of your icon in the
user chooses by Small Icon from the View menu. It also appears in the
Application menu after the user launches your application and in the Apple
menu if the user places your application or an alias to it in the Apple Menu
Items folder. (Alias files and the Apple Menu Items folder are described,
The System Folder and Its Related Directories.)
You can define color versions of both large and small icons by using several
resource types. The resource for each icon variation has the same resource ID
as the 'ICN#' resource that defines the large black-and-white icon. For
example, if the resource ID of your application icon's 'ICN#' resource is 128,
its small black-and-white icon resource, 'ics#', should have a resource ID of
128; and the 'icl4', 'ics4', 'icl8', and 'ics8' resources should also have
resource ID's of 128.
Do not define masks for your color icon resources. The 'icl4' and 'icl8'
resources use the black-and-white icon mask defined in their companion
'ICN#' resource, and the 'ics4' and 'ics8' resources use the black-and-white
icon mask defined in their companion 'ics#' resource. Because of this, the
outline shapes of your color icons should exactly match those defined in your
'ICN#' and 'ics#' resources.
ResEdit 2.1 includes an icon family editor to help you easily manage the
creation of these related resources. See the ResEdit Reference (available from
APDA) for details.
most effective use of color and shape for your icons. Choose your colors from
the 36 recom-mended icon colors in the system palette. (If you use ResEdit
2.1, these colors appear in a palette when you choose Apple Icon Colors from
the Color menu.) Note that you cannot specify your own color table for these as
allows you to define a palette for the system to use when it needs to define the
color environment, you should rely on the system palette colors for your
application is not running and that the user can switch to another application
when your application is running. Relying on the system palette gives your
application is. And because users can change the desktop color and pattern,
your application also gives users more control over their work environment if
your icons rely on the system palette. Users can always alter your color
definitions by selecting an icon and choosing a color from the Label menu. The
Finder then blends the chosen color into those of the selected icon. To re store
the original colors, users must choose None from the Label menu.
If your application creates documents, it should also define at least two
additional icon families: one to be displayed for documents created by your
application, and another to be displayed when the user creates stationery pads
from one of your application's documents.
Your application might also define icons for other types of documents. If your
application should also define an icon family for editions. If your Macintosh
application is a database program or serves as a source for data (as a
spreadsheet program often does), you might wish to create query documents so
that other Macintosh applications can gain access to that data through the
Data Access Manager. In this case, your application should also define an
icon family for its query documents.
If your application creates other variations of its documents, you can assist
your users by providing different icons for the different documents. For
example, TeachText has separate icon families to distinguish its read-only
and graphics documents.
The following figure shows the large black-and-white icons for the various
documents that sample application creates: text, stationery pad, and edition.
Examples of document icons
Defining icon resources is not enough to display your icons. In addition, you
must follow one of two sets of procedures:
• If you are an application developer, you must define
file reference resources and a bundle resource for your application as
described in these sections.
• If you are an information provider or database developer-that is, you
provide documents that are used by other applications-you do not need
to create file reference resources or a bundle resource to provide
document icons on Macintosh computers running System 7.0. You can
instead create customized icons for your documents as described in
Customized Icons. (However, if you want your document to appear
with its own icons on earlier versions of system software, you must
create a file reference resource and a bundle resource as described in
the next two sections.)
PlotCIcon procedures to draw icons. If you use these procedures, note
that they draw only those icons defined by 'ICN#' and 'cicn' resources. These
procedures will not draw any icons that are defined by the icon resources
new to System 7.0-namely, the 'ics#', 'icl4', 'ics4', 'icl8', and 'ics8'
resources.